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Band Objects 

Microsoft® Internet Explorer 4.0 allows an application to define and create bands that are 
displayed within the shell and the browser. 

' Band Object Typ es 
" Implementing a Band Object 

Band Object Types 

Internet Explorer 4.0 currently supports three different types of band objects- Desk Bands 
Explorer Bands , and Communication Bands. Each type ofband serves a Se n^purpose The 
following sections describe these different band types and their capabilities. purpose - 1 ne 

Desk Bands 

Desk Bands are band objects that are displayed as a band in the shell taskbar or as a floatina tool 
window on the desktop. Desk Bands are used to display information and to rece ve inpuf from the 
user They are available to the user throughout the entire Microsoft® Windows® lesston De™k 
Bands are supported in shell versions 4.71 and later. session. uesK 



The following illustration shows a Desk Band on the taskbar. 
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This illustration shows a Desk Band as a floating toolbar. 
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Explorer Bands 

Explorer Bands are band objects that are displayed in a browser window. They usually contain 
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information or supply tools that are helpful to the user while using the browser These bands are 
displayed to the left of the current view and normally receive user incut tiffin ' 
being performed. Explorer Bands are supported in ii^^ m SOme act,on 

The following illustration shows an Explorer Band in Internet Explorer 4.0. 
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Communication Bands 



Communication Bands are band objects that are displayed in a browser window This can hp a 
Windows Explorer window or an Internet Explorer 4.0 browser window. ^ are 
normally used to relay information to the user. These bands are displayed below the current view 
and don't usually accept user input. Communication Bands are supported in browser S!?"nV f ?i 
and later, ~ 

The following illustration shows a Communication Band in Internet Explorer 4.0. 
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Implementing a Band Object 

This section describes the basic steps involved in creating a band object. To receive the mocr 
5KS^"«S5S^' y °° Sh ° Ula 66 ,aml " 8r w ^ COM, U T Z£Z™Z Spo„,„, 

Registering the Band Object 

The band object server must be registered as an OLE in-process server that supports the 
apartment threading model. The default value for the server is a text entry that will be displayed in 
the band select.on menu. The following example shows the required registry entries ' Sp ' ayed m 

HKE Y_CLAS SES_ROOT 
CLSID 

<server clsid> = "&Sample Band" 

InProcServer32 = »<server DLL path and file name>' 

"ThreadingModel » = "Apartment " 

in addition to these entries, the band object server is registered for one or more component 
categories. The registered component categories define the type of band object that the server 
implements. The following list shows the available band object component categories These 
component category identifiers are defined in Shlobj.h. a se 

CATlD_DeskBand The band object implements a Desk Band . 

CATID_lnfoBand The band object implements an Explorer Band . 

CATID_CommBand The band object implements a Communication Band . 
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Band Object Interfaces 

The following interfaces must be implemented by a band object: 

• IDeskBand 

• IObjectWithSite 

• IPersist 

• IPersistStream 

If the band can accept user input, HnputOfrject is also required. And if you want to add to the 
context menu that is displayed for the band, you must implement the iContextMPnn interface. 

Implementing the IDeskBand interface in a band object 

A band object must implement the IPesKBand interface. Because IDeskBand is derived from 
IDockinqWindow , the band object must implement all the methods for both of these interfaces. 
IDockinqWindow is derived from IOIeWindow . The IOIeWindow interface provides the 
GetWindow method so that the container can obtain the band object's window handle. 

The IDockinqWindow methods are used to show, hide, and close the band object window. Unlike a 
normal docking window implementation, a band object does not have to negotiate its border space 
within the band container. Instead, the band container resizes the window provided bv the band 
object's IOIeWindow: :GetWindow method. y 

The band container calls the IDeskBand: :GetBandinfo method to obtain information about the 
band. In response to this method, the band object must provide all of the display band information 
that is being requested. 

Implementing the IObjectWithSite interface in a band object 

A band object must also implement IObiectWithSitP. The band container uses this interface to set 
the band object's site with the SetSite method. The band object should perform the followina steDs 
when its SetSite method is called: y H 

• Release any site pointer that is being maintained. 

• If the site pointer passed to this method is NULL, the band is being removed. The band obiect 
can just return S_OK. J 

• Tf the site pointer passed to this method is not NULL, a new site is beino set. In this case the 
following steps should be performed: 

■ Call Querylnterface on the site interface for IOIeWindow , and call the 
IOIeWindow: :GetWindow method to obtain the parent window of the band object 
window. The IOIeWindow interface must be released if it is no longer needed. 

■ Create the band object window as a child of the parent window obtained in the previous 
step. The window should not be created as a visible window. 

■ Call Querylnterface on the site interface for HnputObjectSite , and maintain this as the 
band object's site pointer. This step is necessary only if the band object implements 
IlnputObject . 

■ If all the previous steps succeeded, the band object should return S_OK. If any of these 
steps failed, the band object should return an OLE-defined error code indicating what 
failed. 



The following example shows a very simple implementation of a SetSite method. 
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S TDMETHOD IMP CBandOb j ect : : SetSite ( IUnknown* punkSite) 

//If a site is being held, release it. 
if (m__pSite) 

{ 

m_pSite->Release ( ) ; 
m_pSite = NULL; 

} 

//If punkSite is not NULL, a new site is being set. 
if (punkSite) 

{ 

//Get the parent window. 
IOleWindow *p01eWindow; 

m_hwndParent = NULL; 

if (SUCCEEDED (punkSite- >QueryInterf ace (IID_I01eWindow, (LPVC 

pOleWindow- >Get Window (&m_hwndParent) ; 
pOleWindow- >Release () ; 

} 

if ( im_hwndParent) 
return E_FAIL; 

if ( i CreateBandWindow (m_hwndParent ) ) 
return E_FAIL; 

//Get and keep the IlnputObjectSite pointer. 

if (SUCCEEDED (punkSite- >QueryInterf ace (IID_IInputObjectSite, 

return S_OK; 

} 

return E_FAIL; 

} 

return S_OK; 

} 



Implementing the IPersist and IPersistStream interfaces in a band object 

The band container uses the IPersist and IPersistStream interfaces to obtain information from the 
band object and to allow the band object to load and/or store any persistent information that it 
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needs. 

dS-en h tme°r n,y ^ method - Getc,assID - w ^n the container uses to obtain the band object's 

lrlrl« n L COntaine J C ?l S ' heband ob J ect ' s IPersistStream methods to allow the band object to save 
or load any persistent data that it requires. If the band object does not have any perstetent data it 
st.N must return success codes from the IPersistStream methods, even if no actionTare 
performed in these methods. ' a,e 

Implementing the IlnputObject interface in a band object 

If a band object accepts user input, it must implement the HnputObiect interface The container 
uses nnputObject and implements HnputQpjectSite to maintain proper us input tous when 
more than one contained window exists. For implementation and usage information see the 
descriptions for the IlnputObject and IlnputObjectSite interfaces mr ° rmat ' 0n ' see the 

Implementing the IContextMenu interface in a band object 

If a band object needs to add items to the context menu that is displayed for the band it must 
implement the IContextMenu interface. The container will obtain the IContextMenu interne 
pointer by call.ng the band object's OuervInterfacP method, requesting IID IConrexWenu The 
container uses the IContextMenu interface to obtain the band-specific wM^^S^Tnd to 
ZS^SFSSZto™ 1 *- imp,ementation 'nformation'see the deSpZs TSZ" ° 

Band Object Site Commands 

The band object container implements an IOIeCommandTampr interface that can be used to send 
commands to the container. This interface is obtained by calling the nnputObie£s?« " 
Querylnterface method requesting IID.IOIeCommandTarget. The IQJeiemmangTajmt- ■ Exec 
method can then be called to send commands to the container. Th e command group is iden^i ed as 
CGID.DeskBand, and the following commands are supported- identified as 

DBID.BANDINFOCHANGED The band's information has changed. The container will call the 

ba " d ' s IPeskBand;:GetBandlpfo method, requesting the updated 
information. The pvaln argument of the IOIeCommandTaroef -Ex er 

method is a VARIANT that contains the band identifier that was 

passed in the most recent call to IDeskBand::GetBandInfo 

DBID_MAXIMIZEBAND The container will maximize the band. The pvaln argument of the 

IOIeCommandTarget: :Fxer method is a VARIANT that contains the 
band identifier that was passed in the most recent call to 
IDeskBand.-GetBandTnfn 
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